Admin API guide #1390

kbatuigas · 2025-10-14T06:08:38Z

Description

This pull request introduces documentation for the new ConnectRPC-powered Admin API endpoints in Redpanda v25.3 and updates navigation and references throughout the docs to surface these changes. The most important changes are the addition of a dedicated Admin API usage guide, updates to the release notes to announce the new endpoints, and improved navigation and reference structure to distinguish between legacy and new Admin API endpoints.

Admin API documentation and navigation improvements:

Added a new page, use-admin-api.adoc, providing a comprehensive guide on managing Redpanda clusters using both legacy and new ConnectRPC Admin API endpoints, including usage examples and authentication details.
Updated navigation in nav.adoc to add direct links to the new Admin API usage guide and the ConnectRPC Admin API reference, making it easier for users to find relevant documentation. [1] [2]
Revised the API reference page to clearly distinguish between legacy (v1) and new ConnectRPC (v2) Admin API endpoints, including versioning details and links to the new usage guide.

Release notes updates:

Announced the introduction of ConnectRPC-powered Admin API endpoints in Redpanda v25.3, listing new features available via these endpoints and clarifying continued support for legacy endpoints.

These changes collectively improve discoverability, clarity, and usability of the Admin API documentation for both new and existing Redpanda users.

Resolves https://redpandadata.atlassian.net/browse/
Review deadline: 16 Oct

Page previews

Manage > Manage Redpanda Using the Admin API
Reference > API Reference
What's New

Checks

New feature
Content gap
Support Follow-up
Small fix (typos, links, copyedits, etc)

netlify · 2025-10-14T06:08:43Z

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	`4d0b3e0`
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/68faff293fe33b00086edfda
😎 Deploy Preview	https://deploy-preview-1390--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2025-10-14T06:09:09Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch DOC-1706-create-user-guide-for-admin-api

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

rockwotj

LGTM! Nice work

modules/get-started/pages/release-notes/redpanda.adoc

modules/manage/pages/use-admin-api.adoc

Feediver1 · 2025-10-16T21:27:33Z

modules/manage/pages/use-admin-api.adoc

+
+Most Admin API operations are also available using xref:get-started:intro-to-rpk.adoc[`rpk`], a CLI tool which interacts with the Admin API under the hood. 
+
+Redpanda version 25.3 introduces a version 2 of the Admin API, powered by https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations introduced starting in version 25.3 are available with Admin API v2 only, and are not backported to Admin API v1. Supported Admin API v1 operations remain available and you can continue to use them per usual (including with rpk v25.3 and later).


I keep seeing v25.3 in other contexts. No big deal, but we should all be on the same page wrt how we do this.

Feediver1 · 2025-10-16T21:28:24Z

modules/manage/pages/use-admin-api.adoc

+
+Most Admin API operations are also available using xref:get-started:intro-to-rpk.adoc[`rpk`], a CLI tool which interacts with the Admin API under the hood. 
+
+Redpanda version 25.3 introduces a version 2 of the Admin API, powered by https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations introduced starting in version 25.3 are available with Admin API v2 only, and are not backported to Admin API v1. Supported Admin API v1 operations remain available and you can continue to use them per usual (including with rpk v25.3 and later).


Suggested change

Redpanda version 25.3 introduces a version 2 of the Admin API, powered by https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations introduced starting in version 25.3 are available with Admin API v2 only, and are not backported to Admin API v1. Supported Admin API v1 operations remain available and you can continue to use them per usual (including with rpk v25.3 and later).

Redpanda v25.3 introduces a version 2 of the Admin API, powered by https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations introduced in version 25.3 are available with Admin API v2 only, and are not backported to Admin API v1. Supported Admin API v1 operations remain available and you can continue to use them as usual (including with rpk v25.3 and later).

Feediver1 · 2025-10-16T21:30:54Z

modules/manage/pages/use-admin-api.adoc

+** For Admin API v1, any supported version of Redpanda. For Admin API v2, Redpanda version 25.3 or later.
+* Superuser privileges, if xref:manage:security/authentication.adoc#enable-authentication[authentication] is enabled on your cluster for the Admin API. For more information, see xref:manage:security/authentication.adoc#create-superusers[Configure Authentication]. (Some endpoints are read-only and do not require superuser access.)
+* A tool to make HTTP requests, such as `curl`, or client libraries for your programming language of choice. 
+** For Admin API v2, you can also make requests using a Connect client. You can install the Connect plugin for your preferred language and use the Protobuf compiler to generate an SDK. Admin API v2 is also available as a Buf module and can be accessed through the https://buf.build/redpandadata/core/docs/dev:redpanda.core.admin.v2[Buf Schema Registry]. The https://buf.build/docs/cli/[Buf CLI] provides an easy way to generate client SDKs.


Is this a Kafka Connect? If you are referring generally to connectors, wouldn't this be "connect"?
Or is this Redpanda Connect?

Feediver1 · 2025-10-16T21:32:43Z

modules/manage/pages/use-admin-api.adoc

+** For Admin API v1, any supported version of Redpanda. For Admin API v2, Redpanda version 25.3 or later.
+* Superuser privileges, if xref:manage:security/authentication.adoc#enable-authentication[authentication] is enabled on your cluster for the Admin API. For more information, see xref:manage:security/authentication.adoc#create-superusers[Configure Authentication]. (Some endpoints are read-only and do not require superuser access.)
+* A tool to make HTTP requests, such as `curl`, or client libraries for your programming language of choice. 
+** For Admin API v2, you can also make requests using a Connect client. You can install the Connect plugin for your preferred language and use the Protobuf compiler to generate an SDK. Admin API v2 is also available as a Buf module and can be accessed through the https://buf.build/redpandadata/core/docs/dev:redpanda.core.admin.v2[Buf Schema Registry]. The https://buf.build/docs/cli/[Buf CLI] provides an easy way to generate client SDKs.


Suggested change

** For Admin API v2, you can also make requests using a Connect client. You can install the Connect plugin for your preferred language and use the Protobuf compiler to generate an SDK. Admin API v2 is also available as a Buf module and can be accessed through the https://buf.build/redpandadata/core/docs/dev:redpanda.core.admin.v2[Buf Schema Registry]. The https://buf.build/docs/cli/[Buf CLI] provides an easy way to generate client SDKs.

** For Admin API v2, you can also make requests using a Connect client. You can install the Connect plugin for your preferred language and use the Protobuf compiler to generate an SDK. Admin API v2 is also available as a Buf module, which you can access using the https://buf.build/redpandadata/core/docs/dev:redpanda.core.admin.v2[Buf Schema Registry]. The https://buf.build/docs/cli/[Buf CLI] provides an easy way to generate client SDKs.

Feediver1 · 2025-10-16T21:33:20Z

modules/manage/pages/use-admin-api.adoc

+
+== Choose an Admin API version
+
+In Redpanda version 25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:


I would not mix v and version, especially in the same paragraph

Feediver1 · 2025-10-16T21:33:52Z

modules/manage/pages/use-admin-api.adoc

+
+== Choose an Admin API version
+
+In Redpanda version 25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:


Suggested change

In Redpanda version 25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:

In Redpanda v25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:

Feediver1 · 2025-10-16T21:36:59Z

modules/manage/pages/use-admin-api.adoc

+
+=== Use Admin API v2
+
+The Admin API v2 is built on ConnectRPC, so you can send `curl` requests with a JSON payload, or use a generated Connect client to call the same methods directly from your application code. The v2 paths are the fully qualified names of the services. All v2 endpoints accept POST requests only.


Connect client<--- Redpanda Connect? Kafka Connect? connect client?

modules/manage/pages/use-admin-api.adoc

Feediver1

See suggested updates

kbatuigas · 2025-10-21T02:24:21Z

@mattschumpert Do we want to announce Admin v2 in What's New?

Co-authored-by: Joyce Fee <[email protected]>

Feediver1 · 2025-10-23T19:28:13Z

modules/manage/pages/use-admin-api.adoc

+
+Most Admin API operations are also available using xref:get-started:intro-to-rpk.adoc[`rpk`], a CLI tool that interacts with the Admin API under the hood. 
+
+Redpanda v25.3 introduces new endpoints to the Admin API that are served with https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations available starting in v25.3 are accessible as RPC services through these new endpoints. Existing Admin API operations from versions earlier than 25.3 remain available at the same URLs and you can continue to use them as usual (including with rpk v25.3 and later).


...remain available at the same URLs...
The same URLs as what?

Feediver1 · 2025-10-23T19:29:58Z

modules/manage/pages/use-admin-api.adoc

+== Prerequisites
+
+* A running Redpanda Self-Managed cluster.
+* Superuser privileges, if xref:manage:security/authentication.adoc#enable-authentication[authentication] is enabled on your cluster for the Admin API. For more information, see xref:manage:security/authentication.adoc#create-superusers[Configure Authentication]. (Some endpoints are read-only and do not require superuser access.)


So if I want to know if the endpoints I need to use require superuser access, can I view a list somewhere that tells me which endpoints require it and which ones don't?

All v2 endpoints require superuser, but I don't have a definitive list for v1. Will reach out to an SME - if this list can be put together, these details can be added at a later time

modules/manage/pages/use-admin-api.adoc

Feediver1 · 2025-10-23T20:55:54Z

modules/manage/pages/use-admin-api.adoc

+```
+
+// TODO: Update link if necessary when v2 URLs are finalized
+For a full list of available endpoints, see the link:/api/doc/admin/[Admin API Reference]. Select "v1" in the version selector to view legacy endpoints.


link to the Admin API Reference does not render in html output - throws a Page Not Found

This is a limitation with our Bump-hosted (link:/) pages, they don't get included in the preview build

Feediver1 · 2025-10-23T21:17:53Z

modules/manage/pages/use-admin-api.adoc

+--
+====
+
+=== Use new (ConnectRPC) endpoints


Maybe consider: Use ConnectRPC endpoints

and then put a note explaining what makes them different from v1 endpoints.

modules/manage/pages/use-admin-api.adoc

Feediver1 · 2025-10-23T21:19:55Z

modules/manage/pages/use-admin-api.adoc

+* Shadowing
+* Connected client monitoring
+
+For a full list of available endpoints, see the link:/api/doc/admin/v2/[Admin API Reference]. Select "v2" in the version selector to view the ConnectRPC endpoints.


@mattschumpert I think users are going to be throwing questions our way--we should be up front/transparent about v1 vs v2. If we are not, this will generate questions and may undermine user confidence in the docs.

Co-authored-by: Joyce Fee <[email protected]>

kbatuigas marked this pull request as ready for review October 15, 2025 00:24

kbatuigas requested a review from a team as a code owner October 15, 2025 00:24

kbatuigas requested a review from rockwotj October 15, 2025 00:24

rockwotj approved these changes Oct 15, 2025

View reviewed changes

kbatuigas changed the title ~~Admin v2~~ Admin API guide Oct 16, 2025

Feediver1 reviewed Oct 16, 2025

View reviewed changes

modules/get-started/pages/release-notes/redpanda.adoc Outdated Show resolved Hide resolved

Feediver1 reviewed Oct 16, 2025

View reviewed changes

modules/get-started/pages/release-notes/redpanda.adoc Outdated Show resolved Hide resolved

Feediver1 reviewed Oct 16, 2025

View reviewed changes

modules/manage/pages/use-admin-api.adoc Outdated Show resolved Hide resolved

Feediver1 reviewed Oct 16, 2025

View reviewed changes

modules/manage/pages/use-admin-api.adoc Outdated Show resolved Hide resolved

Feediver1 approved these changes Oct 16, 2025

View reviewed changes

kbatuigas mentioned this pull request Oct 17, 2025

Add Admin v2 spec file redpanda-data/api-docs#29

Merged

kbatuigas requested a review from mattschumpert October 21, 2025 02:23

kbatuigas requested a review from rockwotj October 22, 2025 16:50

rockwotj approved these changes Oct 22, 2025

View reviewed changes

kbatuigas added 6 commits October 22, 2025 11:00

Add pages for Admin v2

ddb12fa

Add to nav tree and clean up links

48c8cac

Apply suggestions from automated review

a6feb20

Add Admin v2 to What's New

29d838b

Edits per review

72f623a

Standardize v for version

51b5b45

kbatuigas and others added 4 commits October 22, 2025 11:03

Apply suggestions from code review

fad611a

Co-authored-by: Joyce Fee <[email protected]>

Missed suggestion

e8f10af

Do not call out v2

43e876f

Update nav and architecture

2d1adde

kbatuigas force-pushed the DOC-1706-create-user-guide-for-admin-api branch from 8b20de2 to 2d1adde Compare October 22, 2025 18:09

Update link

39c32ad

kbatuigas requested a review from Feediver1 October 23, 2025 16:11

Feediver1 reviewed Oct 23, 2025

View reviewed changes

modules/manage/pages/use-admin-api.adoc Outdated Show resolved Hide resolved

Feediver1 reviewed Oct 23, 2025

View reviewed changes

modules/manage/pages/use-admin-api.adoc Outdated Show resolved Hide resolved

Feediver1 reviewed Oct 23, 2025

View reviewed changes

modules/manage/pages/use-admin-api.adoc Outdated Show resolved Hide resolved

Feediver1 reviewed Oct 23, 2025

View reviewed changes

Feediver1 approved these changes Oct 23, 2025

View reviewed changes

kbatuigas and others added 3 commits October 23, 2025 21:17

Apply suggestions from code review

31222b0

Co-authored-by: Joyce Fee <[email protected]>

Apply suggestions from review

6d96473

Reapply suggestions

4d0b3e0

kbatuigas merged commit 2521c4a into beta Oct 24, 2025
7 checks passed

kbatuigas deleted the DOC-1706-create-user-guide-for-admin-api branch October 24, 2025 17:39


		Most Admin API operations are also available using xref:get-started:intro-to-rpk.adoc[`rpk`], a CLI tool which interacts with the Admin API under the hood.

		Redpanda version 25.3 introduces a version 2 of the Admin API, powered by https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations introduced starting in version 25.3 are available with Admin API v2 only, and are not backported to Admin API v1. Supported Admin API v1 operations remain available and you can continue to use them per usual (including with rpk v25.3 and later).


		== Choose an Admin API version

		In Redpanda version 25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:

	In Redpanda version 25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:
	In Redpanda v25.3, Admin API v2 endpoints are entirely exclusive to v2, and there is virtually no overlap in functionality between v2 and v1. You can use both versions of the Admin API on the same cluster, so choosing which version depends on whether you use the following v2-only features:


		=== Use Admin API v2

		The Admin API v2 is built on ConnectRPC, so you can send `curl` requests with a JSON payload, or use a generated Connect client to call the same methods directly from your application code. The v2 paths are the fully qualified names of the services. All v2 endpoints accept POST requests only.


		Most Admin API operations are also available using xref:get-started:intro-to-rpk.adoc[`rpk`], a CLI tool that interacts with the Admin API under the hood.

		Redpanda v25.3 introduces new endpoints to the Admin API that are served with https://connectrpc.com/docs/introduction[ConnectRPC]. New Redpanda features and operations available starting in v25.3 are accessible as RPC services through these new endpoints. Existing Admin API operations from versions earlier than 25.3 remain available at the same URLs and you can continue to use them as usual (including with rpk v25.3 and later).

Uh oh!

Admin API guide #1390

Admin API guide #1390

Uh oh!

Conversation

kbatuigas commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Page previews

Checks

Uh oh!

netlify bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for redpanda-docs-preview ready!

Uh oh!

coderabbitai bot commented Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

rockwotj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Feediver1 Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Feediver1 left a comment

Choose a reason for hiding this comment

Uh oh!

kbatuigas commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kbatuigas commented Oct 14, 2025 •

edited

Loading

netlify bot commented Oct 14, 2025 •

edited

Loading

coderabbitai bot commented Oct 14, 2025 •

edited

Loading

Feediver1 Oct 16, 2025 •

edited

Loading

kbatuigas commented Oct 21, 2025 •

edited

Loading